C/C++ Users Group Library 1996 July/C-C++ Users Group Library July 1996.iso/vol_300/315_01/readme.txt

Text File | 1990-05-14 | 16KB | 238 lines

FTGRAPH.EXE was created to go with my article in _Intelligent Instruments and
Computers_. ("Understanding and Using Fast Fourier Transforms", Thomas Clune,
_II&C_ v.7 n.3, May/June, 1989, p.103 ff). That article explains the concepts
that are behind the FTGRAPH.EXE package, and should be considered part of
the documentation for FTGRAPH's use. This file is intended as an aid to
installation and configuration of FTGRAPH, not as a "user manual" for people
unfamiliar with the FT and its uses.

FTGRAPH.EXE is a set of utilities for performing Fourier transforms and
inverse Fourier transforms.  The minimum requirements for program operation
are: an IBM PC, XT, AT, or clone, 256 K or more RAM, MS-DOS or PC-DOS, v.2.0
or later.  The program will use a numerical coprocessor (8087, 80287, or
80387) if it is present, but does not require it.  The program supports any of
the standard graphics screen adaptors (Hercules, CGA, EGA, and VGA graphics are
supported). Note Well: if you are using a Hercules Graphics adaptor, you must
install MSHERC.COM for graphics support.  MSHERC is a Microsoft program, but
is distributed here with Microsoft's permission.  Or, you can output HPGL files
(HPGL, Hewlett-Packard Graphics Language, is the language used by HP-compatible
plotters.)  Various devices support HPGL.  For example, at the Institute we
often send HPGL files to a Hewlett-Packard LaserJet, using a utility marketed
by HP (LaserPlotter, from Insight Development Corp.).  This is an easy way to
get high-quality graphics out of different devices.  NOTE THAT FTGRAPH DOES NOT
OUTPUT HPGL DATA TO A PLOTTER.  Rather, it creates a file of HPGL data that
can then be copied to the graphics output device using either a utility like
LaserPlotter or, if you are outputting to an HP-compatible plotter, by
using the DOS COPY command.  For example, if the HP plotter is attached
to COM1: and you have set the MODE command to be compatible with the plotter
settings (see DOS manual), just COPY yourfile.plt COM1 at the DOS prompt.

In order for FTGRAPH to work properly, you must be operating under ANSI.SYS.
This is a terminal control program that comes with DOS.  To install ANSI.SYS,
you must have a line DEVICE=ANSI.SYS in your CONFIG.SYS file, and the ANSI.SYS
program must be in the root directory of your boot disk.  See the DOS manual
for details.

The file FTGRAPH.CNF is a configuration file that must be located in the same
directory as FTGRAPH.EXE.  There are six arguments in the file.  They are:
1. The first number is a floating-point value that specifies the smallest
amplitude that the program will consider as significant when you use polar
coordinates (amplitude/phase) for your transform.  This value
is used to decide whether the phase argument is significant, or just noise.
An FFT will calculate phase even if there is no signal at the given frequency,
so this value is used to decide whether phase should be set to 0 because there
really isn't any signal there.  It does not apply to rectangular format data
transforms (real/imaginary).
2. The second number is an integer used as a flag to tell the program whether
you want to use the entire transform (both positive and negative frequencies)
or just the positive frequencies.  Often, if you are using real data, you
will limit your frequency display to positive values.  However, there are
times that positive/negative are desirable.  For example, if you are going to
process data in the frequency domain and re-transform it back to the time
domain, you must use both positive and negative frequencies or you will lose
half the data points during transformation. NOTE WELL: to lessen this problem,
I transform data files for filtering as positive/negative, even if you select
positive-only display. Thus, the re-transformed time domain data will contain
the full number of values.
3. The third value is an integer flag that specifies whether you want to use
rectangular coordinates (real/imaginary) or polar (amplitude/phase) coordinates
for your frequency domain data.
4. The fourth value is the units for filter rolloff.  2.0= dB/octave, 10.0=
dB/decade.
5. The fifth argument is the number of decimals (INTEGER ARGUMENT) that you
want to use in your floating-point printer dumps of data files (either [seconds,
magnitude] or [frequency, magnitude] files).  This number is for printer
display ONLY, and does not affect the precision of calculation in the program.
6. The last value is an integer flag that specifies whether you want to be
able to select from the menu using only keyboard inputs or both mouse
(Microsoft compatible only) and keyboard.  NOTE WELL: if you use the mouse,
the RIGHT-HAND button is used to enter your selection.  Moving the mouse
will move the highlight to the choice you want to make.  WARNING: If you set
this variable to 1 (enable mouse operation) and a valid mouse is not installed
on your computer, the program will hang, and may display a FLOATING POINT
COPROCESSOR UNDERFLOW error message.  Always disable the mouse option in the
configuration file if you do not have a Microsoft(-like) mouse on your system.
Remember that you must have a line like DEVICE=MOUSE.SYS in your CONFIG.SYS
file in order to install the mouse device driver.

All these arguments are explained in the FTGRAPH.CNF file itself.  You may
edit the file with a common word processor to customize the package to your
taste.  WARNING: Do not capriciously move from positive to positive/negative,
or polar to rectangular coords.  The program does not keep a record of which
format was used with which data file.  The current settings ARE ASSUMED TO
BE THE CORRECT ONES for the data file under analysis.  If a file was collected
using positive only settings, and transformed under the positive/negative
format, for example, it will assume that the file contains both positive and
negative data.  Similarly, there is nothing in the file that identifies the
data as time-domain or frequency domain, etc.  Establish a format that
is right for your applications, and stick with it.  Since the right format
for display is often different from the right format for data processing, as
explained above, FTGRAPH allows you to change the default settings within
the program by selecting menu item B.  NOTE WELL: resetting defaults using
menu item B applies only as long as the program is running.  When you load
FTGRAPH, it reads its initial conditions from FTGRAPH.CNF, so the only way
to make changes in configuration permanent is by editing that file.

The data files that are read by this program must have the following format:
The files are plain ASCII text files,and the first line of the file contains
three numbers.  First is an integer specifying how many data points are in the
file.  The program expects a power of 2 size data set ONLY.  If the number of
points in the data set is not a power of 2, the program will automatically
zero-fill the working set (not the disk data) to the next highest power of two.
The second and third number are floating point numbers used to scale graphs if
they will be something other than full-scale. The second number is the minimum
y value of the graph scale, and the third number is the maximum y value for
the graph. Note that you can set multiple graphs to the same scale by making
these numbers the same in the various data sets. This lets you compare
magnitudes across graphs. Also, if you wish to expand the scale of a graph,
this feature will let you clip the graph at min and max values of your choice.
Alternatively, you may set both the min and max values to the same value. This
serves as a flag to the program to autoscale the graph to fill the screen. As
a convention, I suggest using 0 for the min and max if you want to autoscale.
By the way, when FTGRAPH creates a data file the values that it uses for the
minimum and maximum are the actual minimum and maximum of the data set.
All numbers in the data file are separated by white space only (space, tab, or
carriage return).  That is, there are no commas or semicolons allowed.  Aft